Elementos da Aula

  1. Reproducible Research: ir;
  2. Controle de Versão: ir;
  3. Introdução ao GitHub: ir;
  4. R Markdown: ir.

Reproducible Research

O que é reproducible research?

Para alguns, é um termo que representa o fato de todo o achado a partir de um código e um dado poder ser reproduzido de forma identica caso este código e dado esteja disponível. Para outros, a definição é mais ampla, e envolve a noção de que que qualquer cientista usando os mesmos métodos pode chegar a resultados similares e fazer as mesmas inferências sobre um resultado já publicado - é o coração da ciência.


  • Quais os elementos de um trabalho reprodutível (baseado em Ihle et al, 2017, Behav Ecol)?
  1. Reliability (Confiabilidade): o pesquisador testou uma hipótese de forma objetiva (é o padrão de ouro);
    • Falta de Confiabilidade: falha em conduzir a pesquisa de acordo com o plano documentado.
  2. Reproducibility (Reprodutibilidade): dada a mesma questão, dados brutos e métodos, alguém com mesmo conhecimento deve chegar na conclusão;
    • Falta de Reprodutibilidade: falha em garantir que reconduzir o mesmo projeto vai resultar no mesmo achado.
  3. Replicability (Replicabilidade): validação de um experimento e/ou achado através de repetições em estudos independentes.
    • Falta de Replicabilidade: baixa probabilidade de que estudos independentes chegarem ao mesmo resultado.

Apesar de parecer fantástico, a ideia de que estamos em uma crise de reprodutibilidade não é algo tão distante assim…

Fonte: Baker & Penny, 2016, Nature, Is there a reproducibility crisis?


Como identificar se o seu trabalho está sendo afetado pela crise de reprodutibilidade (baseado em Ihle et al, 2017, Behav Ecol)?

  1. Confiabilidade - você já…
    1. tornou o nome das suas amostras não identificável de forma que você não saiba o que esperar delas?
    2. pediu para uma pessoa que não sabe nada sobre a sua hipótese coletar os dados (ou te ajudar)?
    3. continuou amostrando sabendo que existia um resultado nulo, de forma a aumentar o seu poder estatístico, e não reportou esta decisão a posteriori?
    4. reformulou uma hipótese baseado no que você encontrou, e apresentou o achado não esperado ‘fingindo’ que você já predizia ele desde o começo (HARKing - Hypothesis After Results Are Known)?
    5. reportou somente as medidas de interesse e deixou de fora outros que você testou?
    6. excluiu outliers baseado na significância dos seus resultados antes e depois da exclusão?
    7. excluiu, incluiu e transformou covariáveis para achar o melhor modelo, mas só reportou o modelo final?
  2. Reprodutibilidade - você já…
    1. passou um tempão reprocessando e reanalisando os dados sem ser capaz de demonstrar para você ou outrém se todos os passos do processamento e análise foram identicos ao da vez anterior?
    2. achou um erro nos seus resultados sem saber de onde ele veio?
    3. perdeu parte dos dados ou notas sobre como processar os dados e obter outras variáveis de interesse?
    4. esqueceu qual análise você já havia feito?
    5. teve dificuldade de responder estas questões para um revisor, amigo e/ou colaborador?
  3. Replicabilidade - você já…
    1. baseou todo um projeto em um achado sem poder saber se ele é válido na realidade?
    2. foi incapaz de replicar um estudo publicado anteriormente (inclusive, conceitualmente)?
    3. não conseguiu provar que um trabalho este sujeito ao viés de confirmação?

Pseudoscience (Richard P. Feynman): ciência que não é ciência…segue os métodos, segue a forma, mas não chega a lugar algum, não gera leis e nem predições (e.g., a metáfora das pistas de avião; controvérsias alimentares; controvérsias sobre comportamento; controvérsias sobre o funcionamento das coisas).

E tem jeito?

Fonte: Barba, 2016, Science, The hard road to reproducibility?

Fonte: Ihle et al, 2017, Behav Ecol, Striving for transparent and credible research - practical guidelines for behavioral ecologists

Reprodutibilidade é um hábito que pode ser adquirido e, uma vez que você começa a praticar, não tem mais como parar.

Ninguém nasce sabendo a importância dessas coisas, e tão pouco começa a carreira acadêmica sendo treinado em uma carreira de reprodutibilidade. É preciso que nós falemos mais sobre isso, com nossos colaboradores, amigos, amigos de laboratório, orientadores,…é só através do treinamento e da capacitação das pessoas é que nós vamos conseguir fazer melhor.

  • Pequenos hábitos que fazem a diferença:
    • antes de iniciar o seu projeto de pesquisa, descreva as suas hipóteses e/ou objetivos, crie ilustrações mostrando qual é o resultado esperado que você está buscado;
    • anote TUDO o que você fizer e ver de forma padronizada: confeccione cadernos de campo padrão, crie um livro de protocolos,…
    • tabele os seus dados com atenção, cheque de forma dupla se você não está esquecendo de tabelar alguma informação e/ou procure saber com os seus colaboradores e origem da ausência de dados;
    • documente todas as etapas da análise de dados - decisões, escolhas, lógica e caminhos;
    • use um script para limpar seus dados e realizar todo e qualquer tipo de manipulação;
    • use caminhos relativos;
    • use uma ferramenta de controle de versão;

Controle de Versão

A reposta curta: é um programa que acompanha as mudanças feitas em arquivos específicos ao longo do tempo, e mantém um registor de todas as versões anteriores daqueles arquivos.

Quando estamos tabelando um dado, escrevendo um código, gerando os resultados de uma análise ou escrevendo um documento, muitas vezes vamos nos deparar com alguns causos:

  1. manter um arquivo de cópia de cada passo que tomamos ao escrever ou editar algo, só para garantir que temos aquele arquivo original salvo;
  2. ideias relâmpago e dias intensos, em que você vai ficar indo e vindo o tempo todo no que você está trabalhando, mas no final do dia vai querer algo similar ao que você gerou lá no início;
  3. ao compartilhar um código, dado ou outro arquivo com alguém, as pessoas podem fazer edições e não te indicar exatamente o que mudaram OU indicar e você ter que fazer a conferência entre versões manualmente.

Uma forma de lidar com estes (e outros) causos de forma mais fácil é através do uso de um sistema de controle versão (para mais informações, ver: Blischak et al, 2016, PLOS Comp Biol, A quick introduction to version control with Git and GitHub).

Um sistema de controle de versão permite que você mantenha um registro de cada mudança que você fez em um código, dado ou arquivo (desde que ele seja ‘lido’ linha-a-linha). Com isto, você tem a opção de reverter uma mudança que você fez a partir de alguma versão do seu trabalho, além de escrever mensagens para si próprio cada vez que você faz uma destas alterações e faz o controle da versão. Assim, qualquer pessoa que olhe o histórico de desenvolvimento da tarefa consegue entender a lógica que você usou em cada passo do processo criativo. Além disso, um sistema de controle de versão facilita o trabalho colaborativo, uma vez que também permite que seus colaboradores possam incorporar suas próprias contribuições à tarefa diretamente em seu código/dado/arquivo em formato original - e se você não gostar, sabe exatamente onde e quem fez a edição, e pode reverter ela.

Então, com um sistema de controle de versão:

  1. você mantém registro de todas as etapas do processo;
  2. pode retornar a qualquer ponto do histórico de um arquivo;
  3. pode deixar mensagens para você mesmo e outros que indicam a lógico do processo criativo;
  4. colaborações são adicionadas diretamente à tarefa.

Existem vários sistemas de controle de versão, sendo um dos mais conhecidos o Git:


Como funciona este sistema de controle de versão?

Após a instalação e configuração do sistema de controle de versão, podemos prosseguir para entender as etapas do processo, que estão sumarizadas abaixo.

Você começa usando o sistema de controle de versão iniciando um repositório (git init) - local onde ficam todos os arquivos que estão sendo acompanhados e têm seu histórico de mudanças armazenado.

Ao criarmos um repositório vazio, precisamos adicionar os arquivos que estarão sob o processo de controle de versão (git add). Uma vez que tenhamos adicionado estes arquivos ao processo de controle de versão, dizemos que o arquivo foi movido staged - isto é, movemos o arquivo para a staging area, local em que os arquivos são colocados para serem “fotografados” pelo sistema de controle de versão. Após este último passo, nós temos que “fotografar” o(s) arquivo(s) através do processo de commit (git commit) - é a partir desse ponto que a “fotografia” do(s) arquivo(s) é registrada.

Logo, cada vez que você faz uma alteração em um arquivo, você adiciona este arquivo à area de “fotografia” (stage) e “fotografa” a versão do arquivo (commit). Além disso, cada versão que você “fotografa” (commit) um arquivo, você pode usar uma pequena mensagem descrevendo o que aquela “fotografia” representa. Note também que cada vez que cada “fotografia” dos arquivos que foram para o commit recebem um “número de identidade”, que pode ser usado para explorar o histórico e reverter mudanças feitas para cada um daquele momentos.

Assim, toda vez que você fizer uma alteração e salvar um arquivo, o controle de versão vai te indicar que existe uma alteração naquele documento. Você pode stage o documento, então “fotografar” (commit) ele e continuar trabalhando, repetindo indefinidamente o processo. Note, no entanto, que aqui só estamos realizando e salvando o processo de controle de versão no nosso próprio computador.

Fonte: Blischak et al, 2016, PLOS Computational Biology, A quick introduction to version control with Git and GitHub

Introdução ao GitHub

O GitHub é um serviço de hospedagem para repositórios que estão sob controle de versão. Você pode fazer o upload do seu repositório para uma conta pessoal na internet, o que facilita o seu próprio acesso e de seus colaboradores ao projeto de trabalho.

  • Quais as vantagens?
  1. É um backup virtual dos seus arquivos, que está disponível na “nuvem” (similar ao Dropbox);
  2. Além da funcionalidade similar ao Dropbox, também permite que você faça o controle de versão, eliminando muito dos problemas de usar o Dropbox;
  3. Facilita o trabalho colaborativo entre colaboradores e com outros pesquisadores em todo o mundo;
  4. Você pode ter repositórios públicos e privados (necessário pagar, mas…);

Após cadastrar a sua conta no GitHub, o processo de controle de versão ganha mais alguns elementos e etapas. Em primeiro lugar, assim como você adicionou um grupo de arquivos a um repositório local (origin), você precisa copiar este respositório para um repositório remoto (remote; git remote add), que fica hospedado no servido do GitHub. Aqui, também precisamos adicionar (add) e commit cada alteração feita em um arquivo, para que o controle de versão se torne efetivo. Entretanto, as mudanças que você faz no seu repositório origin precisam ser enviada para o repositório remote (remote). Para tal, você “empurra” (push; git push) os seus arquivos e commits para o repositório remoto. Note que voccê não precisa empurrar estes arquivos toda vez que você faz um commit - você pode ir trabalhando e, no momento que julgar oportuno, “empurrar” tudo de uma vez para o repositório remoto.

Fonte: Blischak et al, 2016, PLOS Computational Biology, A quick introduction to version control with Git and GitHub

Além de criar repositórios remotos sob tudo o que acontece em seu repositório local, você também pode criar cópias dos repositórios públicos de outras pessoas (e de repositórios privados compartilhados com você). Quando fazemos isso, estamos abrindo um ramo do repositório original (fork), que é um cópia identica de tudo o que já aconteceu com aquele repositório, e colocando ele em nosso repositório remoto. Uma vez que criamos este fork, podemos clonar o repositório para o nosso repositório local (clone; git clone). Assim, podemos fazer um trabalho, contribuir, alterar os arquivos e tudo o mais, fazer nossos commits, “empurrar” tudo de volta ao repositório remoto e criar um pedido de fusão com o repositório original (pull request).

Assim, fechamos um ciclo de criar um sistema mais colaborativo e transparente para a manipulação e manutenção de dados, além de facilitar a colaboração entre diferentes pesquisadores.

Fonte: Blischak et al, 2016, PLOS Computational Biology, A quick introduction to version control with Git and GitHub


R markdown

  • O que é?

O Markdown é uma ferramenta de conversão de texto para HTML usado por escritores da internet. O Markdown te permite que você leia e escreva documentos de forma fácil, e então converta o resultado em um arquivo XHTML (ou HTML) estruturalmente válido (John Gruber, criador do Markdown).

  • As principais vantagens de escrever em Markdown são:
    • Te permite focar em escrever, ao invés de formatar;
    • Elementos para formatação são mínimos, mas intuitivos;
    • Fácil de coverter para outros formatos de documento, dado o uso de algumas ferramentas;
    • Pode ser integrado à outras linguagens de programação.
  • Assim, o R Markdown é uma integração das funcionalidades do Markdown com o código do R:
    • Documentos contém pedaços “vivos” de código do R;
    • O código do R é avaliado, rodado e adicionado ao processo de criação do arquivo final;
    • Resultados do processamento são apresentados diretamente no documento.

Ou seja, se você está lendo um arquivo feito em R Markdown, e pode ver todo o código do R sendo usado e gerando resultados, é porque o script que gerou aquele documento é totalmente funcional e não apresenta defeitos de processamento.

  • Para usar o R Markdown aqui, você só precisa ter instalado os pacotes knitr e markdown:
    • knitr: converte o texto escrito no arquivo markdown;
    • markdown: converte o arquivo markdown em vários tipos de formato.
  • O que você pode criar em Markdown?
    • páginas HTML;
    • arquivos de PDF;
    • apresentações de slide;
    • arquivos com extensão de uso do Word;
    • slides interativos;
  • Como escrever:
    • Help -> Markdown Quick Reference: guia básico
    • Help -> Cheatsheets -> R Markdown Cheat Sheet: guia completo
    • Help -> Cheatsheets -> R Markdown Reference Guide: guia aprofundado